Introduce include_code function.

include_code has four optional arguments:

• The start_line integer, 1 by default: the real one!
• The end_line number, None by default
• The indent_level integer, 0 by default: how many times four spaces are added in front of the lines, mainly used for boxes and tabs
• The remove_indent boolean, False by default: to remove has much indentation as possible

new include_code VS old include_file

• include_code doesn't end with its new line feed while include_file does which complicate concatenating slices or inserting hard coded lines like ellipsis comments
• include_code starts with the first line real number while include_file need to decrease it by one

Examples

• converted docs/search/search_api.md shows in several places how line feeds are easier to control.
• converted docs/api/rest_api/rest_api_usage/rest_requests.md shows two indent_level usage, one as the third argument, one as the only named argument.
• converted docs/administration/recent_activity/recent_activity.md validates remove_indent (used as a named argument)
• converted docs/templating/twig_function_reference/image_twig_functions.md shows that it works with .md files too (it was starting on an empty line)

Update tools/code_samples/code_samples_usage.php to also report include_code changes.
While on it, also update it to handle named parameters like, for example, remove_indent=True.

This is a manually generate diff:
code_samples_usage.diff.html

It also shows that 5.0 version fails on remove_indent=True
I added code_samples/api/product_catalog/src/Command/ProductCommand.php for more test cases.

Here is the whole file list I checked for include usage on 5.0 and include_code branches to generate the diff:

• code_samples/api/product_catalog/src/Command/ProductCommand.php
• code_samples/api/public_php_api/src/Command/FilterCommand.php
• code_samples/api/public_php_api/src/Command/FilterLocationCommand.php
• code_samples/api/public_php_api/src/Command/FindByTaxonomyEmbeddingCommand.php
• code_samples/api/public_php_api/src/Command/FindComplexCommand.php
• code_samples/api/public_php_api/src/Command/FindContentCommand.php
• code_samples/api/public_php_api/src/Command/FindInTrashCommand.php
• code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php
• code_samples/api/public_php_api/src/Controller/CustomController.php
• code_samples/api/public_php_api/src/Controller/CustomFilterController.php
• code_samples/api/public_php_api/src/Controller/PaginationController.php
• code_samples/api/public_php_api/templates/themes/standard/full/custom_pagination.html.twig
• code_samples/api/rest_api/create_image.json.php
• code_samples/api/rest_api/create_image.xml.php
• code_samples/recent_activity/config/append_to_services.yaml
• code_samples/recent_activity/src/ActivityLog/ClassNameMapper/MyFeatureNameMapper.php
• code_samples/recent_activity/src/Command/ActivityLogContextTestCommand.php
• code_samples/recent_activity/src/Command/MonitorRecentContentCreationCommand.php
• code_samples/recent_activity/src/EventSubscriber/MyFeatureEventSubscriber.php
• code_samples/recent_activity/src/EventSubscriber/MyFeaturePostActivityListLoadEventSubscriber.php
• code_samples/recent_activity/templates/themes/admin/activity_log/ui/default.html.twig
• code_samples/recent_activity/templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig
• docs/templating/twig_function_reference/field_twig_functions.md

Locally, I tested "removing indents but one" with success:

docs/tmp.yaml

k1.1:
    k2.1: v2.1
    k2.2:
        k2.2.1: v2.2.1
        k2.2.2: v2.2.2
        k2.2.3:
            k2.2.3.1: v2.2.3.1
            k2.2.3.2: v2.2.3.2
    k2.3: v2.3
k1.2: v1.2

doc.tmp.md

# TMP

=== "YAML"

    ``` yaml
    [[= include_file('docs/tmp.yaml', 3, 8, '    ', True) =]]
    ```
    ``` yaml
    [[= include_code('docs/tmp.yaml', 4, 8, 1, True) =]]
    ```

Locally, it works visually on /en/latest/tmp/ and in a terminal with php tools/code_samples/code_samples_usage.php docs/tmp.yaml

% php tools/code_samples/code_samples_usage.php docs/tmp.yaml

docs/tmp.yaml

docs/tmp.md@5:    ``` yaml
docs/tmp.md@6:    [[= include_file('docs/tmp.yaml', 3, 8, '    ', True) =]]
docs/tmp.md@7:    ```

001⫶    k2.2.1: v2.2.1
002⫶    k2.2.2: v2.2.2
003⫶    k2.2.3:
004⫶        k2.2.3.1: v2.2.3.1
005⫶        k2.2.3.2: v2.2.3.2

docs/tmp.md@8:    ``` yaml
docs/tmp.md@9:    [[= include_code('docs/tmp.yaml', 4, 8, 1, True) =]]
docs/tmp.md@10:    ```

001⫶    k2.2.1: v2.2.1
002⫶    k2.2.2: v2.2.2
003⫶    k2.2.3:
004⫶        k2.2.3.1: v2.2.3.1
005⫶        k2.2.3.2: v2.2.3.2

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Redirects cover removed/moved pages
• Code samples are working
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR